Skip to main content

Availability

In order to access the APIs, you should target a site through its URL along with:

  • http://[site-url]/api/exports/v1/{endpoint} for exporting and indexing endpoints,
  • http://[site-url]/api/v1/system/{endpoint} for webhooks and event payloads, and
  • http://[site-url]/api/v1/{endpoint} for endpoints related to referentials.

In the previous examples, endpoint corresponds to the action you are calling.

API specifications

Response and Request Formats​

  • These APIs work only with JSON as their transport format.
  • All JSON properties are named in camel case starting by lower case (e.g. customFields).
  • Dates follow the ISO 8601 standard.

Implementation Recommendations

  • The number of API calls must be kept to a minimum.
  • Errors must be corrected.
  • Request only one token for a given user session. Avoid requesting a new token between each API call and only request a new token when the current one has expired (the duration is mentioned in the authorization response, in the field expires_in - see below in the Authorization section).

Authorization

In order to interact with the APIs, the application will need to be identified through a client_id and a client_secret, using the url http://[site-url]/api/token. You will get a token that must be in the Authorization header of each API call.

The protocol involved is OAuth2.

How to retrieve a token​

  • “As an application”:
    • POST https://[site-url]/api/token HTTP/1.1
    • Content-Type: application/x-www-form-urlencoded
    • In the body:
        - client_id=[clientID]
        - client_secret=[clientSecret]
        - grant_type=client_credentials
        - scope=MatchingIndexation

The client_id and client_secret are unique per partner and per environment and can be configured by a Cegid technical consultant.

The response will contain the access token:

{
     "access_token": "433fKaLfINnJB46DhWIVFyoVmPzX3h7ZUauAfOaT046KyXqd0qFIkAa3MOAHHYgHKU9tF",
     "token_type": "bearer",
     "expires_in": 1199
}

The token obtained must be used in the Authorization header of every API call:

Authorization: bearer token, where token is the token retrieved.

How to use the access token​

  • GET /api/exports/v1/candidates
    • In headers:
    Authorization = bearer 433fKaLfINnJB46DhWIVFyoVmPzX3h7ZUauAfOaT046KyXqd0qFIkAa3MOAHHYgHKU9tF

Cinematics

The cinematics presented below concern the process of data exchange and indexing. For information on how the matching process can be implemented, please see the documentation page, sections 5 and 6.

Note: To avoid any confusion, it must be noted that

  • the object candidate in the APIs corresponds to applicant, and
  • the object offer corresponds to vacancy.

Cinematic of API calls to get all referentials needed for initialization​

  1. Retrieve a token “as an application” (grant_type=client_credentials): POST /api/token
  2. Get all referentials, by category (example for countries referential): GET /api/v1/referentials/countries
  3. Get referentials translations using the id of a specific item. Two cases:
    • Get all available translations of referential item: GET /api/referentials/countries/{id}/translations
    • Get the item's translation in one specific language: GET /api/referentials/countries/{id}/translations/{lcid}

Cinematic of API calls to retrieve vacancies and applicants to supply the indexing engine​

  1. Retrieve a token “as an application” (grant_type=client_credentials): POST /api/token
  2. Retrieve all available vacancies: GET /api/exports/v1/vacancies
  • Indexation of vacancies on partner side
  1. Retrieve all applicants: GET /api/exports/v1/candidates
  • Indexation of applicants on partner side
  1. Report on indexed data: POST /api/exports/v1/reports (see example in the end of the document)

We propose that you use the above cinematic only in the initialization process. After having retrieved the initial information you can keep the vacancies and applicants lists up-to-date by using webhooks (see next section).

Note: For the list of all available endpoints, more technical details on the Matching Indexation APIs as well as the full list of available referentials please visit the Cegid documentation page on this topic.

Use of Webhooks

The use of webhooks is available for Matching Indexation which allows you to get notified when there are changes such as new vacancies/applicants or modifications on existing vacancies/applicants. You can subscribe to an event in order to receive notifications when the event is triggered.

By default, the mechanism to call peers to inform them of any change is triggered every 15 minutes but can be modified by the client.

To register to an event you must first retrieve a token “as an application” (grant_type=client_credentials): POST /api/token.

To subscribe to the event you must call the endpoint: POST /api/system/v1/webhooks

In the body of the request you must specify the event you want to subscribe to, a callback URL on which Recruiting may call the subscriber and a ping URL on which Recruiting may call when a ping is requested. For example if you want to get notified when new vacancies are available:

POST /api/system/v1/webhooks
Authorization: Bearer /* Oauth2 token */

{
 "event": "vacancy_new",
 "callbackUrl": "https://example.com/api/talentsoft/v1/events",
 "pingUrl": "https://example.com/api/talentsoft/v1/pingevents" 
}

The response will contain a hookId which can be used to unsubscribe from the event using the endpoint: DELETE /api/system/v1/webhooks/{hookId}

Note: Some events which may be useful for matching indexation are vacancy_new, application_event_new, vacancy_update. For the complete list of webhook events available for subscription please visit this page.

Example of the body of a request for reporting indexed data​

To report on the results of indexing using the endpoint POST /api/exports/v1/reports the request body should be of the following structure:

{ 
    "reportType": "vacancies", 
    "items": [ 
        { 
            "id": "50557b07-a608-4f7f-9620-e1a580be35e1", 
            "date": "2019-05-16T11:38:37Z", 
            "lastUpdateDate": "2019-05-16T11:38:37Z", 
            "status": "success" 
        }, 
        { 
            "id": "9d6baf1a-889a-48c5-a5eb-b2d936c998b6", 
            "date": "2019-05-15T10:30:42Z", 
            "lastUpdateDate": "2019-05-16T11:38:37Z", 
            "status": "error", 
            "messages": [
                { "The url does not respond." }
            ] 
        } 
    ] 
}

The report contains the reportType, which can have one of the values "vacancies" or "candidates", and a list of items where:

  • id is the username of the applicant or the reference of a vacancy,
  • date and lastUpdateDate are the creation and last update dates respectively,
  • status is the indexation status of the specific item (success/error), and
  • messages is a list of messages, only if in error status.

For more information on the reporting please visit this page.